📤 API de Meios de Envio - Documentação Completa

📋 Visão Geral

A API de Meios de Envio é responsável por toda a gestão de meios de envio de mensagens no sistema CordenaAi. Esta API permite configurar diferentes tipos de canais de comunicação (email, SMS, push notification, etc.), definir suas características visuais, ordem de exibição e configurações específicas. O sistema substitui os meios de envio hardcoded por uma solução dinâmica e flexível.

🎯 Endpoints Disponíveis

📝 Gestão de Meios de Envio

1. GET /api/meios-envio

Listar Meios de Envio Ativos

2. GET /api/meios-envio/todos

Listar Todos os Meios de Envio

3. GET /api/meios-envio/{id}

Obter Meio de Envio por ID

4. POST /api/meios-envio

Criar Novo Meio de Envio

5. PUT /api/meios-envio/{id}

Atualizar Meio de Envio

6. DELETE /api/meios-envio/{id}

Excluir Meio de Envio

🔧 Modelo de Dados

Estrutura do MeioEnvioConfig

{
  "id": "integer",
  "nome": "string",
  "descricao": "string",
  "icone": "string",
  "cor": "string",
  "ativo": "boolean",
  "ordemExibicao": "integer",
  "requerConfiguracao": "boolean",
  "configuracoes": "string",
  "usuarioCriacao": "string",
  "criacao": "datetime",
  "usuarioAtualizacao": "string",
  "atualizacao": "datetime"
}

Estrutura do CriarMeioEnvioRequest

{
  "nome": "string",
  "descricao": "string",
  "icone": "string",
  "cor": "string",
  "ativo": "boolean",
  "ordemExibicao": "integer",
  "requerConfiguracao": "boolean",
  "configuracoes": "string"
}

Estrutura do AtualizarMeioEnvioRequest

{
  "id": "integer",
  "nome": "string",
  "descricao": "string",
  "icone": "string",
  "cor": "string",
  "ativo": "boolean",
  "ordemExibicao": "integer",
  "requerConfiguracao": "boolean",
  "configuracoes": "string"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Configuração de Novos Canais

POST /api/meios-envio
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "WhatsApp Business",
  "descricao": "Envio de mensagens via WhatsApp Business API",
  "icone": "fab fa-whatsapp",
  "cor": "#25D366",
  "ativo": true,
  "ordemExibicao": 3,
  "requerConfiguracao": true,
  "configuracoes": "{\"apiKey\":\"\",\"phoneNumber\":\"\"}"
}

2. Listagem para Interface de Usuário

GET /api/meios-envio
Authorization: Bearer {token}

3. Atualização de Configurações

PUT /api/meios-envio/2
Content-Type: application/json
Authorization: Bearer {token}

{
  "id": 2,
  "nome": "Email Corporativo",
  "descricao": "Envio via servidor SMTP corporativo",
  "icone": "fas fa-envelope",
  "cor": "#007bff",
  "ativo": true,
  "ordemExibicao": 1,
  "requerConfiguracao": true,
  "configuracoes": "{\"smtp\":\"smtp.empresa.com\",\"port\":587}"
}

4. Gestão Administrativa

GET /api/meios-envio/todos
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo de Configuração de Novo Meio

  1. Validação de dados no backend pela própria API
  2. POST /api/meios-envio com dados validados
  3. Verificação de unicidade do nome
  4. Definição automática da ordem de exibição
  5. Criação do registro no banco de dados
  6. Retorno do objeto criado com ID

Fluxo de Uso na Interface

  1. GET /api/meios-envio para obter meios ativos
  2. Renderização na interface com ícones e cores
  3. Seleção pelo usuário na criação de mensagem
  4. Validação dos meios selecionados
  5. Processamento do envio através dos meios

Configurações Específicas por Meio

{
  "email": {
    "smtp": "smtp.gmail.com",
    "port": 587,
    "ssl": true,
    "username": "[email protected]"
  },
  "sms": {
    "provider": "twilio",
    "accountSid": "AC...",
    "authToken": "..."
  },
  "whatsapp": {
    "apiKey": "...",
    "phoneNumber": "+5511999999999",
    "webhook": "https://api.domain.com/webhook"
  }
}

🔧 Implementação Técnica

Migração de Hardcoded para Dinâmico

A implementação substitui os meios de envio hardcoded por uma tabela dinâmica:

Scripts de Inicialização

-- Inserção de meios de envio iniciais
INSERT INTO MeiosEnvio (Nome, Descricao, Icone, Cor, Ativo, OrdemExibicao, RequerConfiguracao)
VALUES 
('Email', 'Envio por correio eletrônico', 'fas fa-envelope', '#007bff', 1, 1, 1),
('SMS', 'Envio por mensagem de texto', 'fas fa-sms', '#28a745', 1, 2, 1),
('Push Notification', 'Notificação push no aplicativo', 'fas fa-bell', '#ffc107', 1, 3, 0);

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi